home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Languguage OS 2
/
Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO
/
gnu
/
elispman.lha
/
elispman
/
elisp-36
(
.txt
)
< prev
next >
Wrap
GNU Info File
|
1993-05-11
|
50KB
|
777 lines
This is Info file elisp, produced by Makeinfo-1.52 from the input file
elisp.texi.
This file documents GNU Emacs Lisp.
This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 19.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: elisp, Node: GNU Emacs Internals, Next: Standard Errors, Prev: Tips, Up: Top
GNU Emacs Internals
*******************
This chapter describes how the
runnable Emacs executable is dumped with the preloaded Lisp libraries
in it, how storage is allocated, and some internal aspects of GNU Emacs
that may be of interest to C programmers.
* Menu:
* Building Emacs:: How to preload Lisp libraries into Emacs.
* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
* Object Internals:: Data formats of buffers, windows, processes.
* Writing Emacs Primitives:: Writing C code for Emacs.
File: elisp, Node: Building Emacs, Next: Pure Storage, Prev: GNU Emacs Internals, Up: GNU Emacs Internals
Building Emacs
==============
The first step in building Emacs
is to compile the C sources. This produces a program called `temacs',
also called a "bare impure Emacs". It contains the Emacs Lisp
interpreter and I/O routines, but not the editing commands.
Then, to create a working Emacs
editor, issue the `temacs -l loadup' command. This directs `temacs' to
evaluate the Lisp files specified in the file `loadup.el'. These files
set up the normal Emacs editing environment, resulting in an Emacs
which is still impure but no longer bare.
It takes a long time to load the
standard Lisp files. Luckily, you don't have to do this each time you
run Emacs; `temacs' can dump out an executable program called `emacs'
which has these files preloaded. `emacs' starts more quickly because
it does not need to load the files. This is the program that is
normally installed.
To create `emacs', use the
command `temacs -batch -l loadup dump'. The purpose of `-batch' here
is to prevent `temacs' from trying to initialize any of its data on the
terminal; this ensures that the tables of terminal information are
empty in the dumped Emacs.
When the `emacs' executable is
started, it automatically loads the user's `.emacs' file, or the
default initialization file `default.el' if the user has none. (*Note
Starting Up::.) With the `.emacs' file, you can produce a version of
Emacs that suits you and is not the same as the version other people
use. With `default.el', you can customize Emacs for all the users at
your site who don't choose to customize it for themselves. (For further
reflection: why is this different from the case of the barber who shaves
every man who doesn't shave himself?)
On some systems, dumping does not
work. Then, you must start Emacs with the `temacs -l loadup' command
each time you use it. This takes a long time, but since you need to
start Emacs once a day at most--and once a week or less frequently if
you never log out--the extra time is not too severe a problem.
Before `emacs' is dumped, the
documentation strings for primitive and preloaded functions (and
variables) need to be found in the file where they are stored. This is
done by calling `Snarf-documentation' (*note Accessing
Documentation::.). These strings were moved out of `emacs' to make it
smaller. *Note Documentation Basics::.
- Function: dump-emacs TO-FILE
FROM-FILE
This function dumps the current
state of Emacs into an
executable file TO-FILE. It
takes symbols from FROM-FILE
(this is normally the
executable file `temacs').
If you use this function in an
Emacs that was already dumped,
you must set
`command-line-processed' to
`nil' first for good results.
*Note Command Line Arguments::.
- Command: emacs-version
This function returns a string
describing the version of Emacs
that is running. It is useful
to include this string in bug
reports.
(emacs-version)
=> "GNU Emacs 18.36.1 of Fri Feb 27 1987 on slug
(berkeley-unix)"
Called interactively, the
function prints the same
information in the echo area.
- Variable: emacs-build-time
The value of this variable is
the time at which Emacs was
built at the local site.
emacs-build-time
=> "Fri Feb 27 14:55:57 1987"
- Variable: emacs-version
The value of this variable is
the version of Emacs being run.
It is a string, e.g.
`"18.36.1"'.
File: elisp, Node: Pure Storage, Next: Garbage Collection, Prev: Building Emacs, Up: GNU Emacs Internals
Pure Storage
============
There are two types of storage in
GNU Emacs Lisp for user-created Lisp objects: "normal storage" and
"pure storage". Normal storage is where all the new data which is
created during an Emacs session is kept; see the following section for
information on normal storage. Pure storage is used for certain data
in the preloaded standard Lisp files: data that should never change
during actual use of Emacs.
Pure storage is allocated only
while `temacs' is loading the standard preloaded Lisp libraries. In
the file `emacs', it is marked as read-only (on operating systems which
permit this), so that the memory space can be shared by all the Emacs
jobs running on the machine at once. Pure storage is not expandable; a
fixed amount is allocated when Emacs is compiled, and if that is not
sufficient for the preloaded libraries, `temacs' crashes. If that
happens, you will have to increase the compilation parameter `PURESIZE'
in the file `config.h'. This normally won't happen unless you try to
preload additional libraries or add features to the standard ones.
- Function: purecopy OBJECT
This function makes a copy of
OBJECT in pure storage and
returns it. It copies strings
by simply making a new string
with the same characters in
pure storage. It recursively
copies the contents of vectors
and cons cells. It does not
make copies of symbols, or any
other objects, but just returns
them unchanged. It signals an
error if asked to copy markers.
This function is used only
while Emacs is being built and
dumped; it is called only in
the file
`emacs/lisp/loaddefs.el'.
- Variable: pure-bytes-used
The value of this variable is
the number of bytes of pure
storage allocated so far.
Typically, in a dumped Emacs,
this number is very close to
the total amount of pure
storage available--if it were
not, we would preallocate less.
- Variable: purify-flag
This variable determines
whether `defun' should make a
copy of the function definition
in pure storage. If it is
non-`nil', then the function
definition is copied into pure
storage.
This flag is `t' while loading
all of the basic functions for
building Emacs initially
(allowing those functions to be
sharable and non-collectible).
It is set to `nil' when Emacs
is saved out as `emacs'. The
flag is set and reset in the C
sources.
You should not change this flag
in a running Emacs.
File: elisp, Node: Garbage Collection, Next: Writing Emacs Primitives, Prev: Pure Storage, Up: GNU Emacs Internals
Garbage Collection
==================
When a program creates a list or
the user defines a new function (such as by loading a library), then
that data is placed in normal storage. If normal storage runs low,
then Emacs asks the operating system to allocate more memory in blocks
of 1k bytes. Each block is used for one type of Lisp object, so
symbols, cons cells, markers, etc. are segregated in distinct blocks in
memory. (Vectors, buffers and certain other editing types, which are
fairly large, are allocated in individual blocks, one per object, while
strings are packed into blocks of 8k bytes.)
It is quite common to use some
storage for a while, then release it by, for example, killing a buffer
or deleting the last pointer to an object. Emacs provides a "garbage
collector" to reclaim this abandoned storage. (This name is
traditional, but "garbage recycler" might be a more intuitive metaphor
for this facility.)
The garbage collector operates by
scanning all the objects that have been allocated and marking those
that are still accessible to Lisp programs. To begin with, all the
symbols, their values and associated function definitions, and any data
presently on the stack, are accessible. Any objects which can be
reached indirectly through other accessible objects are also accessible.
When this is finished, all
inaccessible objects are garbage. No matter what the Lisp program or
the user does, it is impossible to refer to them, since there is no
longer a way to reach them. Their space might as well be reused, since
no one will notice. That is what the garbage collector arranges to do.
Unused cons cells are chained
together onto a "free list" for future allocation; likewise for symbols
and markers. The accessible strings are compacted so they are
contiguous in memory; then the rest of the space formerly occupied by
strings is made available to the string creation functions. Vectors,
buffers, windows and other large objects are individually allocated and
freed using `malloc'.
Common Lisp note: unlike other
Lisps, GNU Emacs Lisp does not
call the garbage collector when
the free list is empty.
Instead, it simply requests the
operating system to allocate
more storage, and processing
continues until
`gc-cons-threshold' bytes have
been used.
This means that you can make
sure that the garbage collector
will not run during a certain
portion of a Lisp program by
calling the garbage collector
explicitly just before it
(provided that portion of the
program does not use so much
space as to force a second
garbage collection).
- Command: garbage-collect
This command runs a garbage
collection, and returns
information on the amount of
space in use. (Garbage
collection can also occur
spontaneously if you use more
than `gc-cons-threshold' bytes
of Lisp data since the previous
garbage collection.)
`garbage-collect' returns a
list containing the following
information:
((USED-CONSES . FREE-CONSES)
(USED-SYMS . FREE-SYMS)
(USED-MARKERS . FREE-MARKERS)
USED-STRING-CHARS
USED-VECTOR-SLOTS
(USED-FLOATS . FREE-FLOATS))
(garbage-collect)
=> ((3435 . 2332) (1688 . 0) (57 . 417) 24510 3839 (4 . 1))
Here is a table explaining each
element:
USED-CONSES
The number of cons cells
in use.
FREE-CONSES
The number of cons cells
for which space has been
obtained from the
operating system, but that
are not currently being
used.
USED-SYMS
The number of symbols in
use.
FREE-SYMS
The number of symbols for
which space has been
obtained from the
operating system, but that
are not currently being
used.
USED-MARKERS
The number of markers in
use.
FREE-MARKERS
The number of markers for
which space has been
obtained from the
operating system, but that
are not currently being
used.
USED-STRING-CHARS
The total size of all
strings, in characters.
USED-VECTOR-SLOTS
The total number of
elements of existing
vectors.
USED-FLOATS
The number of floats in
use.
FREE-FLOATS
The number of floats for
which space has been
obtained from the
operating system, but that
are not currently being
used.
- User Option: gc-cons-threshold
The value of this variable is
the number of bytes of storage
that must be allocated for Lisp
objects after one garbage
collection in order to request
another garbage collection. A
cons cell counts as eight bytes,
a string as one byte per
character plus a few bytes of
overhead, and so on. (Space
allocated to the contents of
buffers does not count.) Note
that the new garbage collection
does not happen immediately
when the threshold is
exhausted, but only the next
time the Lisp evaluator is
called.
The initial threshold value is
100,000. If you specify a
larger value, garbage
collection will happen less
often. This reduces the amount
of time spent garbage
collecting, but increases total
memory use. You may want to do
this when running a program
which creates lots of Lisp data.
You can make collections more
frequent by specifying a
smaller value, down to 10,000.
A value less than 10,000 will
remain in effect only until the
subsequent garbage collection,
at which time `garbage-collect'
will set the threshold back to
10,000.
- Function: memory-limit
This function returns the
address of the last byte Emacs
has allocated, divided by 1024.
We divide the value by 1024 to
make sure it fits in a Lisp
integer.
You can use this to get a
general idea of how your
actions affect the memory usage.
File: elisp, Node: Writing Emacs Primitives, Next: Object Internals, Prev: Garbage Collection, Up: GNU Emacs Internals
Writing Emacs Primitives
========================
Lisp primitives are Lisp
functions implemented in C. The details of interfacing the C function
so that Lisp can call it are handled by a few C macros. The only way
to really understand how to write new C code is to read the source, but
we can explain some things here.
An example of a special form is
the definition of `or', from `eval.c'. (An ordinary function would
have the same general appearance.)
DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
"Eval args until one of them yields non-NIL, then return that value.\n\
The remaining args are not evalled at all.\n\
If all args return NIL, return NIL.")
(args)
Lisp_Object args;
{
register Lisp_Object val;
Lisp_Object args_left;
struct gcpro gcpro1;
if (NULL(args))
return Qnil;
args_left = args;
GCPRO1 (args_left);
do
{
val = Feval (Fcar (args_left));
if (!NULL (val))
break;
args_left = Fcdr (args_left);
}
while (!NULL(args_left));
UNGCPRO;
return val;
}
Let's start with a precise
explanation of the arguments to the `DEFUN' macro. Here are the
general names for them:
DEFUN (LNAME, FNAME, SNAME, MIN, MAX, INTERACTIVE, DOC)
LNAME
This is the name of the Lisp
symbol to define with this
function; in the example above,
it is `or'.
FNAME
This is the C function name for
this function. This is the
name that is used in C code for
calling the function. The name
is, by convention, `F'
prepended to the Lisp name,
with all dashes (`-') in the
Lisp name changed to
underscores. Thus, to call this
function from C code, call
`For'. Remember that the
arguments must be of type
`Lisp_Object'; various macros
and functions for creating
values of type `Lisp_Object'
are declared in the file
`lisp.h'.
SNAME
This is a C variable name to
use for a structure that holds
the data for the subr object
that represents the function in
Lisp. This structure conveys
the Lisp symbol name to the
initialization routine that will
create the symbol and store the
subr object as its definition.
By convention, this name is
always FNAME with `F' replaced
with `S'.
MIN
This is the minimum number of
arguments that the function
requires. For `or', no
arguments are required.
MAX
This is the maximum number of
arguments that the function
accepts. Alternatively, it can
be `UNEVALLED', indicating a
special form that receives
unevaluated arguments. A
function with the equivalent of
an `&rest' argument would have
`MANY' in this position. Both
`UNEVALLED' and `MANY' are
macros. This argument must be
one of these macros or a number
at least as large as MIN. It
may not be greater than six.
INTERACTIVE
This is an interactive
specification, a string such as
might be used as the argument
of `interactive' in a Lisp
function. In the case of `or',
it is 0 (a null pointer),
indicating that `or' cannot be
called interactively. A value
of `""' indicates an interactive
function taking no arguments.
DOC
This is the documentation
string. It is written just
like a documentation string for
a function defined in Lisp,
except you must write `\n\' at
the end of each line. In
particular, the first line
should be a single sentence.
After the call to the `DEFUN'
macro, you must write the list of argument names that every C function
must have, followed by ordinary C declarations for them. Normally, all
the arguments must be declared as `Lisp_Object'. If the function has
no upper limit on the number of arguments in Lisp, then in C it
receives two arguments: the number of Lisp arguments, and the address
of a block containing their values. These have types `int' and
`Lisp_Object *'.
Within the function `For' itself,
note the use of the macros `GCPRO1' and `UNGCPRO'. `GCPRO1' is used to
"protect" a variable from garbage collection--to inform the garbage
collector that it must look in that variable and regard its contents as
an accessible object. This is necessary whenever you call `Feval' or
anything that can directly or indirectly call `Feval'. At such a time,
any Lisp object that you intend to refer to again must be protected
somehow. `UNGCPRO' cancels the protection of the variables that are
protected in the current function. It is necessary to do this
explicitly.
For most data types, it suffices
to know that one pointer to the object is protected; as long as the
object is not recycled, all pointers to it remain valid. This is not
so for strings, because the garbage collector can move them. When a
string is moved, any pointers to it that the garbage collector does not
know about will not be properly relocated. Therefore, all pointers to
strings must be protected across any point where garbage collection may
be possible.
The macro `GCPRO1' protects just
one local variable. If you want to protect two, use `GCPRO2' instead;
repeating `GCPRO1' will not work. There are also `GCPRO3' and `GCPRO4'.
In addition to using these
macros, you must declare the local variables such as `gcpro1' which
they implicitly use. If you protect two variables, with `GCPRO2', you
must declare `gcpro1' and `gcpro2', as it uses them both. Alas, we
can't explain all the tricky details here.
Defining the C function is not
enough; you must also create the Lisp symbol for the primitive and
store a suitable subr object in its function cell. This is done by
adding code to an initialization routine. The code looks like this:
defsubr (&SUBR-STRUCTURE-NAME);
SUBR-STRUCTURE-NAME is the name you
used as the third argument to `DEFUN'.
If you are adding a primitive to
a file that already has Lisp primitives defined in it, find the
function (near the end of the file) named `syms_of_SOMETHING', and add
that function call to it. If the file doesn't have this function, or
if you create a new file, add to it a `syms_of_FILENAME' (e.g.,
`syms_of_myfile'). Then find the spot in `emacs.c' where all of these
functions are called, and add a call to `syms_of_FILENAME' there.
This function `syms_of_FILENAME'
is also the place to define any C variables which are to be visible as
Lisp variables. `DEFVAR_LISP' is used to make a C variable of type
`Lisp_Object' visible in Lisp. `DEFVAR_INT' is used to make a C
variable of type `int' visible in Lisp with a value that is an integer.
Here is another function, with
more complicated arguments. This comes from the code for the X Window
System, and it demonstrates the use of macros and functions to
manipulate Lisp objects.
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
Scoordinates_in_window_p, 2, 2,
"xSpecify coordinate pair: \nXExpression which evals to window: ",
"Return non-nil if POSITIONS is in WINDOW.\n\
\(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
Returned value is list of positions expressed\n\
relative to window upper left corner.")
(coordinate, window)
register Lisp_Object coordinate, window;
{
register Lisp_Object xcoord, ycoord;
if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
CHECK_WINDOW (window, 2);
xcoord = Fcar (coordinate);
ycoord = Fcar (Fcdr (coordinate));
CHECK_NUMBER (xcoord, 0);
CHECK_NUMBER (ycoord, 1);
if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
|| (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
+ XINT (XWINDOW (window)->width))))
{
return Qnil;
}
XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
if (XINT (ycoord) == (screen_height - 1))
return Qnil;
if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
|| (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
+ XINT (XWINDOW (window)->height)) - 1))
{
return Qnil;
}
XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
return (Fcons (xcoord, Fcons (ycoord, Qnil)));
}
Note that you cannot directly
call functions defined in Lisp as, for example, the primitive function
`Fcons' is called above. You must create the appropriate Lisp form,
protect everything from garbage collection, and `Feval' the form, as
was done in `For' above.
`eval.c' is a very good file to
look through for examples; `lisp.h' contains the definitions for some
important macros and functions.
File: elisp, Node: Object Internals, Prev: Writing Emacs Primitives, Up: GNU Emacs Internals
Object Internals
================
GNU Emacs Lisp manipulates many
different types of data. The actual data are stored in a heap and the
only access that programs have to it is through pointers. Pointers are
thirty-two bits wide in most implementations. Depending on the
operating system and type of machine for which you compile Emacs,
twenty-four to twenty-six bits are used to address the object, and the
remaining six to eight bits are used for a tag that identifies the
object's type.
Because all access to data is
through tagged pointers, it is always possible to determine the type of
any object. This allows variables to be untyped, and the values
assigned to them to be changed without regard to type. Function
arguments also can be of any type; if you want a function to accept
only a certain type of argument, you must check the type explicitly
using a suitable predicate (*note Type Predicates::.).
* Menu:
* Buffer Internals:: Components of a buffer structure.
* Window Internals:: Components of a window structure.
* Process Internals:: Components of a process structure.
File: elisp, Node: Buffer Internals, Next: Window Internals, Prev: Object Internals, Up: Object Internals
Buffer Internals
----------------
Buffers contain fields not
directly accessible by the Lisp programmer. We describe them here,
naming them by the names used in the C code. Many are accessible
indirectly in Lisp programs via Lisp primitives.
`name'
The buffer name is a string
which names the buffer. It is
guaranteed to be unique. *Note
Buffer Names::.
`save_modified'
This field contains the time
when the buffer was last saved,
as an integer. *Note Buffer
Modification::.
`modtime'
This field contains the
modification time of the
visited file. It is set when
the file is written or read.
Every time the buffer is written
to the file, this field is
compared to the modification
time of the file. *Note Buffer
Modification::.
`auto_save_modified'
This field contains the time
when the buffer was last
auto-saved.
`last_window_start'
This field contains the
`window-start' position in the
buffer as of the last time the
buffer was displayed in a
window.
`undodata'
This field points to the
buffer's undo stack. *Note
Undo::.
`syntax_table_v'
This field contains the syntax
table for the buffer. *Note
Syntax Tables::.
`downcase_table'
This field contains the
conversion table for converting
text to lower case. *Note Case
Table::.
`upcase_table'
This field contains the
conversion table for converting
text to upper case. *Note Case
Table::.
`case_canon_table'
This field contains the
conversion table for
canonicalizing text for
case-folding search. *Note
Case Table::.
`case_eqv_table'
This field contains the
equivalence table for
case-folding search. *Note
Case Table::.
`display_table'
This field contains the
buffer's display table, or
`nil' if it doesn't have one.
*Note Display Tables::.
`markers'
This field contains the chain
of all markers that point into
the buffer. At each deletion
or motion of the buffer gap,
all of these markers must be
checked and perhaps updated.
*Note Markers::.
`backed_up'
This field is a flag which
tells whether a backup file has
been made for the visited file
of this buffer.
`mark'
This field contains the mark
for the buffer. The mark is a
marker, hence it is also
included on the list `markers'.
*Note The Mark::.
`local_var_alist'
This field contains the
association list containing all
of the variables local in this
buffer, and their values. The
function
`buffer-local-variables'
returns a copy of this list.
*Note Buffer-Local Variables::.
`mode_line_format'
This field contains a Lisp
object which controls how to
display the mode line for this
buffer. *Note Mode Line
Format::.
File: elisp, Node: Window Internals, Next: Process Internals, Prev: Buffer Internals, Up: Object Internals
Window Internals
----------------
Windows have the following
accessible fields:
`frame'
The frame that this window is
on.
`mini_p'
Non-`nil' if this window is a
minibuffer window.
`height'
The height of the window,
measured in lines.
`width'
The width of the window,
measured in columns.
`buffer'
The buffer which the window is
displaying. This may change
often during the life of the
window.
`dedicated'
Non-`nil' if this window is
dedicated to its buffer.
`start'
The position in the buffer
which is the first character to
be displayed in the window.
`pointm'
This is the value of point in
the current buffer when this
window is selected; when it is
not selected, it retains its
previous value.
`left'
This is the left-hand edge of
the window, measured in
columns. (The leftmost column
on the screen is column 0.)
`top'
This is the top edge of the
window, measured in lines.
(The top line on the screen is
line 0.)
`next'
This is the window that is the
next in the chain of siblings.
`prev'
This is the window that is the
previous in the chain of
siblings.
`force_start'
This is a flag which, if
non-`nil', says that the window
has been scrolled explicitly by
the Lisp program. At the next
redisplay, if point is off the
screen, instead of scrolling
the window to show the text
around point, point will be
moved to a location that is on
the screen.
`hscroll'
This is the number of columns
that the display in the window
is scrolled horizontally to the
left. Normally, this is 0.
`use_time'
This is the last time that the
window was selected. The
function `get-lru-window' uses
this field.
`display_table'
The window's display table, or
`nil' if none is specified for
it.
(.txt)
(.txt)